home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / mcomm530.arc / SUPLMNT.DOC < prev    next >
Text File  |  1990-09-08  |  38KB  |  878 lines
  1.  
  2.  
  3.  
  4.  
  5.          ===============================================================
  6.  
  7.                           MCOMM SUPPLEMENTAL FUNCTIONS
  8.                   Mike Dumdei, 6 Holly Lane, Texarkana TX 75503
  9.  
  10.          ===============================================================
  11.  
  12.          The functions described in this document are non-async related
  13.          functions provided as part of the MCOMM library.  MCOMM is
  14.          first and foremost a serial I/O library, therefore, much more
  15.          effort went into describing the use of the async functions than
  16.          you will find here.  Also, because MCOMM is a serial library,
  17.          most of the supplemental functions are targeted towards commun-
  18.          ications programs.  The video functions correctly handle all
  19.          ANSI sequences commonly used by BBS systems.  They also support
  20.          windowed output, allowing you to limit the area of the screen
  21.          that will be written to.  For example, you can reserve the
  22.          bottom line of the screen for a status line and no writes, ANSI
  23.          clear screen commands, etc., will be allowed to overwrite or
  24.          erase it.
  25.  
  26.             ANSI sequences supported are:
  27.                CUP - cursor position
  28.                HVP - horizontal, vertical position
  29.                CUU - cursor up
  30.                CUD - cursor down
  31.                CUF - cursor forward
  32.                CUB - cursor backward
  33.                SCP - save cursor position
  34.                RCP - restore cursor position
  35.                ED  - erase display
  36.                EL  - erase line
  37.                SGR - set graphics rendition (colors)
  38.                FF  - form feed, not really ANSI, clears the screen
  39.  
  40.          Tabs, newlines, carriage returns, line feeds, backspace, the
  41.          bell character, etc. are supported also.  See the 'Global Video
  42.          Variables' section for information on options available for
  43.          handling control characters, scrolling, etc.
  44.  
  45.          In addition to the video routines, there are also timeout
  46.          functions, crc functions, string functions, a carrier watchdog
  47.          function, and several others.  On the following pages, the
  48.          video functions are listed first followed by the non-video type
  49.          functions.
  50.  
  51.          Distribution policy:
  52.             These functions are part of the MCOMM async library and may
  53.          not be distributed without the remaining MCOMM files.  No part
  54.          of the registered version may be distributed or used except as
  55.          stated in the license agreement.
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.          GLOBAL VIDEO VARIABLES:
  63.  
  64.          v_seg - segment  address of video RAM, set by initvid()
  65.          v_mode - current video mode, set by initvid()
  66.          v_page - current video page, set by initvid()
  67.          v_color - attribute to use when displaying chars, this variable
  68.             is set directly by ANSI sequences that change the displayed
  69.             attribute and can be set from your C program to change the
  70.             current attribute (def = 7)
  71.          v_snow - snow flag, if 1 chars are written to screen during
  72.             vertical retrace, if 0 chars are written without waiting for
  73.             retrace
  74.          v_cga - a CGA video system was detected
  75.          v_bios - BIOS video flag, if 1 screen writes are performed
  76.             using BIOS INT 10, if 0 screen writes are done directly to
  77.             video RAM
  78.          v_wndsz - current window borders, set by SETWND macro
  79.             (def = 0,0,24,79)
  80.          v_btmrgt, v_rgt, v_btm, v_toplft, v_lft, v_top -
  81.             v_wndsz individual components
  82.          vs_wndsz - limits for d_msgat(), d_nchat(), & d_atrbat()
  83.          vs_btmrgt, vs_toplft  - vs_wndsz individual components
  84.          v_scrlm - scroll mode, if 1 then the window is scrolled when
  85.             the cursor would move off the bottom, if 0 the cursor wraps
  86.             back to the top  (def = 1)
  87.          v_cntrlm - control char handling, if 1 then control chars per-
  88.             form control functions, if 0 control chars are displayed as
  89.             graphic characters (def = 1)
  90.          v_textm - text mode, if 1 newlines are translated to CR/LF
  91.             pairs, if 0 newlines are displayed as LFs (def=1)
  92.          v_ansi - ansi mode, if 1 ANSI sequences are recognized, if 0
  93.             ANSI sequences are not recognized (def = 1)
  94.          v_wrel - if 1 cursor location arguments for functions that are
  95.             limited to the current window are relative to the top left
  96.             of the current window, if 0 cursor locations are absolute
  97.             (def = 0)
  98.          vs_wrel - if 1 cursor location arguments for functions that are
  99.             NOT limited to the current window are relative to the top
  100.             left of the current window, if 0 cursor locations are
  101.             absolute (def = 0)
  102.          v_ansiseq - shows that an ANSI sequence is currently in process
  103.             -- an ESC has been received by the display functions but the
  104.             terminating alpha character has not yet been received. (EX:
  105.             \33[0;36m is an ANSI sequence.  'v_ansiseq' is set to some
  106.             positive value when the ESC character is received and stay
  107.             positive until the sequence terminator is received.  When
  108.             the terminator is received, 'v_ansiseq' is set to a negative
  109.             value.  If the next character displayed after the terminator
  110.             is not the start of another ANSI sequence, 'v_ansiseq' is
  111.             reset to 0 after displaying that character.  This variable
  112.             is useful when stripping ANSI sequences from an incoming
  113.             stream of characters or when it is necessary to interrupt an
  114.             inprocess ANSI sequence.
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.          HANDLING OF UNSUPPORTED ANSI SEQUENCES:
  122.  
  123.          When an unsupported ANSI sequence is displayed, the ESC
  124.          character (a small back arrow), will be displayed followed by
  125.          the unrecognized terminating character.  The characters between
  126.          the ESC and unrecognized terminator are not displayed.
  127.  
  128.  
  129.          INTERRUPTING INPROCESS ANSI SEQUENCES:
  130.  
  131.          This section suggests some possible methods for handling the
  132.          situation where an ANSI sequence is in progress and it is nec-
  133.          essary to display characters that are not part of the sequence
  134.          and then resume the sequence.  An example of where this situa-
  135.          tion is a terminal program that is displaying incoming data
  136.          containing ANSI codes and the user of the program presses a key
  137.          that requires screen output in the middle of one of those
  138.          codes:
  139.                 Incoming data:    ESC[0;  (beginning of ANSI code)
  140.                 User keypress:     F1     (user wants a help screen)
  141.                 More incoming:    36m     (completion of ANSI code)
  142.  
  143.          The ANSI handler in the video library sees this:
  144.                   ESC[0;+----------------+
  145.                         |  Help Screen   |
  146.                         +----------------+36m
  147.          and since it doesn't know what to to with an ANSI code that
  148.          looks like that you see a small back arrow (for unrecognized
  149.          ANSI code), the help screen, and a 36m.
  150.  
  151.          To avoid this problem, you can do one of three things.  The
  152.          first is you can ignore the local user input until the
  153.          inprocess ANSI sequence is completed.  The v_ansiseq variable
  154.          described previously can be used to test whether or not an ANSI
  155.          sequence is currently in process.  Example:
  156.             if (KBHIT()) {
  157.                while (v_ansiseq && ((ch = rx_timeout(1)) != TIMED_OUT))
  158.                   d_ch(ch);
  159.                proc_keypress();
  160.             }
  161.  
  162.          The second method is to use the 'd_msgat' function to display
  163.          local strings.  It automatically save the ANSI sequence status,
  164.          and the present cursor position before displaying the passed
  165.          string.  On exit, the current status of any inprocess ANSI
  166.          sequences and the cursor position are restored.  It will also
  167.          place strings outside the current window making it the best
  168.          function for updating the terminal status line and displaying
  169.          local screens and messages.
  170.  
  171.          The last option is to manually preserve the v_ansiseq variable,
  172.          display local messages, and then manually restore v_ansiseq:
  173.             temp = v_ansiseq, v_ansiseq = 0;
  174.             displayhelp();
  175.             v_ansiseq = temp;
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.          VIDEO MACROS:
  183.  
  184.          ---------------------------------------------------------------
  185.          SETWND(top, left, btm, rgt)  -- Set Window Dimensions
  186.          ---------------------------------------------------------------
  187.          This macro is used to set the global variable that defines the
  188.          screen area that will be affected by the majority of the video
  189.          functions.  Initially set to 0,0,24,79.
  190.  
  191.  
  192.          ---------------------------------------------------------------
  193.          SETTOPLFT(top, lft), SETBTMRGT(btm, rgt)
  194.          ---------------------------------------------------------------
  195.          Same as above but only sets one corner.
  196.  
  197.  
  198.          ---------------------------------------------------------------
  199.          SETsWND(top, left, btm, rgt) -- Set Screen Dimensions
  200.          ---------------------------------------------------------------
  201.          Sets the screen limits for the functions that are allowed to
  202.          write outside the current window.
  203.  
  204.  
  205.          ---------------------------------------------------------------
  206.          SETsTOPLFT(top, lft), SETsBTMRGT(btm, rgt)
  207.          ---------------------------------------------------------------
  208.          Same as SETsWND but for one corner only.
  209.  
  210.  
  211.          ---------------------------------------------------------------
  212.          SCRBUF(rows, cols)
  213.          ---------------------------------------------------------------
  214.          Returns a value that is the required buffer size for the
  215.          pu_scrnd and fpu_scrnd functions.  It is used like this:
  216.  
  217.            sbuf = malloc(SCRBUF(25,80));
  218.            if (sbuf != NULL)
  219.               pu_scrnd(0, 0, 25, 80);
  220.  
  221.  
  222.          ---------------------------------------------------------------
  223.          d_strnat(row,col,char,attrib,count)
  224.          ---------------------------------------------------------------
  225.          Macro for compatibility with older versions of ANSIDRV.
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.          VIDEO FUNCTIONS:
  233.  
  234.          ---------------------------------------------------------------
  235.          initvid -- Initializes Video Variables
  236.          ---------------------------------------------------------------
  237.             int initvid(void);
  238.  
  239.          Initializes the global video variables, v_seg, v_mode, v_page,
  240.          and v_snow.  You MUST call this function before using any of
  241.          the other video functions.  Calling 'initvid' does not
  242.          automatically cause the linker to pull in the code for the
  243.          remaining ANSI video routines.  Initvid only includes the
  244.          global variables and enough code to initialize those variables.
  245.  
  246.  
  247.          ---------------------------------------------------------------
  248.          loc -- Locate the Cursor
  249.          ---------------------------------------------------------------
  250.             void loc(int row, int col);
  251.  
  252.          Locates the cursor at row, col.  The top left of the screen is
  253.          0,0.  If an attempt is made to locate the cursor outside the
  254.          current window the cursor is placed on the window edge closest
  255.          to the passed location.  Setting the global variable 'v_wrel'
  256.          to a non-zero value will make location 0,0 be the top, left
  257.          corner of the current window.
  258.  
  259.  
  260.          ---------------------------------------------------------------
  261.          d_strat -- Display String At Specified Location
  262.          ---------------------------------------------------------------
  263.             void d_strat(int row, int col, char *string);
  264.  
  265.          This function displays a string at row, col.  The attribute
  266.          used is the current value of the global variable 'v_color'.
  267.          The area where the string can be displayed is limited to the
  268.          current window (set by SETWND).
  269.  
  270.  
  271.          ---------------------------------------------------------------
  272.          d_str  -- Display String At Current Location
  273.          ---------------------------------------------------------------
  274.             void d_str(char *string);
  275.  
  276.          Displays a string at the current cursor position using v_color
  277.          for the attribute.
  278.  
  279.  
  280.          ---------------------------------------------------------------
  281.          d_chat -- Display Char At Specified Location
  282.          ---------------------------------------------------------------
  283.             void d_chat(int row, int col, char ch);
  284.  
  285.          Displays one character at the specified position using v_color
  286.          for the attribute.
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.          ---------------------------------------------------------------
  294.          d_ch -- Display Char at Current Location
  295.          ---------------------------------------------------------------
  296.             void d_ch(char ch);
  297.  
  298.          Display one character at the present cursor position using
  299.          v_color for the attribute.
  300.  
  301.  
  302.          ---------------------------------------------------------------
  303.          d_msgat -- Display Message At Location
  304.          ---------------------------------------------------------------
  305.             void d_msgat(int row, int col, int atrib, char *str);
  306.  
  307.          Displays string at the specified location using the specified
  308.          attribute.  This routine is not limited to writing within the
  309.          current window.  It is limited by the variable set by the
  310.          SETsWND macro (s stands for screen).  The routine does not move
  311.          the cursor and does not break up in process ANSI sequences.
  312.          Used to display strings outside the current window.
  313.  
  314.  
  315.          ---------------------------------------------------------------
  316.          d_msgatd -- Display Message At Location Direct Write
  317.          ---------------------------------------------------------------
  318.             void d_msgatd(int row, int col, int atrib, char *str);
  319.  
  320.          This routine writes 'str' at the specified location using the
  321.          given attribute.  Unlike the previous function, this function
  322.          does not support ANSI or control characters.  It is for
  323.          displaying strings on the screen in the fastest possible
  324.          manner.  The 'v_bios' variable described in the list of global
  325.          variables does not apply to this function.  It always uses
  326.          direct screen writes.
  327.  
  328.  
  329.          ---------------------------------------------------------------
  330.          d_atrbat -- Display Attribute At Location With Count
  331.          ---------------------------------------------------------------
  332.             void d_atrbat(int row, int col, int atrb, int count);
  333.  
  334.          Resets the displayed attribute at the specified location to the
  335.          given attribute for the given number of locations.  This rout-
  336.          ine performs like d_msgat() in regard to window limitations,
  337.          cursor movement, and ANSI sequences.
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.          ---------------------------------------------------------------
  345.          d_nchat -- Display Char At Location With Count
  346.          ---------------------------------------------------------------
  347.             void d_nchat(char row, char col, char ch, char atrb,
  348.              int nbr, char dir);
  349.  
  350.          Displays 'ch', 'nbr' times, using 'atrb' for the attribute, at
  351.          'row, col'.  If 'dir' is 0 the chars are displayed vertically
  352.          otherwise they are displayed horizontally.  This routine
  353.          performs like d_msgat in regard to window limitations, cursor
  354.          movement, and ANSI sequences.
  355.  
  356.  
  357.          ---------------------------------------------------------------
  358.          pu_scrnd -- Move Specified Screen Region To A Buffer
  359.          ---------------------------------------------------------------
  360.             void pu_scrnd(int row, int col, int nrows, int ncols,
  361.              char *buf);
  362.  
  363.          This function saves a section of the video display beginning at
  364.          'row', 'col', that is 'nrows' high and 'ncols' wide.  It also
  365.          saves the current cursor position and shape.  The buffer to
  366.          hold the screen information must be (2 * nrows * ncols) + 16
  367.          bytes in size.  The 'v_bios' variable does not apply to this
  368.          function.  It operates in direct write mode only.
  369.  
  370.  
  371.          ---------------------------------------------------------------
  372.          po_scrnd -- Restore a Screen Saved by 'pu_scrnd' Function
  373.          ---------------------------------------------------------------
  374.             void po_scrnd(char *buf);
  375.  
  376.          Restores the screen and cursor information that was placed in
  377.          'buf' by a previous pu_scrnd call.  The 'v_bios' function does
  378.          not apply to this function.
  379.  
  380.  
  381.          ---------------------------------------------------------------
  382.          fpu_scrnd -- Move Specified Screen Region To A FAR Buffer
  383.          ---------------------------------------------------------------
  384.             void fpu_scrnd(int row, int col, int nrows, int ncols,
  385.              char _far *buf);
  386.  
  387.          Same as pu_scrnd except moves screen information to a FAR
  388.          buffer.
  389.  
  390.          ---------------------------------------------------------------
  391.          fpo_scrnd -- Restore a Screen Saved by 'fpu_scrnd' Function
  392.          ---------------------------------------------------------------
  393.             void fpo_scrnd(char _far *buf);
  394.  
  395.          Same as po_scrnd except restores data pushed by 'fpo_scrnd'.
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.          ---------------------------------------------------------------
  403.          pushscrn -- Move Specified Screen Region To A Buffer      ( C )
  404.          ---------------------------------------------------------------
  405.             int pushscrn(int row, int col, int nrows, int ncols);
  406.  
  407.          C function that utilizes pu_scrnd and malloc to build a last in
  408.          first out stack of up to 10 screens.  Performs the same as
  409.          pu_scrnd except automatically allocates the buffer space.
  410.          C source code is included for this function.  Returns 0 if
  411.          successful, non-zero if an attempt is made to push too many
  412.          screens or the call to malloc space for the screen data fails.
  413.  
  414.  
  415.          ---------------------------------------------------------------
  416.          popscrn -- Restore Last Screen Saved by 'pushscrn'        ( C )
  417.          ---------------------------------------------------------------
  418.             int popscrn(void);
  419.  
  420.          Restores last screen pushed by pushscrn function.  Returns 0 if
  421.          successful or non-zero if an attempt is made to pop a screen
  422.          when no more screens remain in the screen stack.
  423.  
  424.  
  425.          ---------------------------------------------------------------
  426.          fpushscrn -- Move Specified Screen Region To FAR Buffer   ( C )
  427.          ---------------------------------------------------------------
  428.             int fpushscrn(int row, int col, int nrows, int ncols);
  429.  
  430.          Same as pushscrn except the screen buffers are allocated from
  431.          far memory using your compiler's version of a far malloc
  432.          function.  (MSC _fmalloc, Turbo C = farmalloc).  Source code is
  433.          included if you are using a compiler that has a different name
  434.          for the function to do this.
  435.  
  436.  
  437.          ---------------------------------------------------------------
  438.          fpopscrn -- Restore Last Screen Saved by 'fpushscrn'      ( C )
  439.          ---------------------------------------------------------------
  440.             int fpopscrn(void);
  441.  
  442.          Same as popscrn except restores last screen pushed by
  443.          fpushscrn.
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.          ---------------------------------------------------------------
  451.          moveblk -- Move Screen To Buffer / Buffer To Screen
  452.          ---------------------------------------------------------------
  453.             void moveblk(int row, int col, int nrows, int ncols,
  454.              char *buf, int dirflag);
  455.  
  456.          This function does the same thing as pu_scrnd and po_scrnd
  457.          combined except it does not save data on the cursor position or
  458.          shape and all args are needed when both saving and restoring.
  459.          The 'dirflag' determines which direction the data is to be
  460.          moved.  If it is NZ, data is transferred from the screen to the
  461.          buffer.  If it is zero, then buffer data is transferred to the
  462.          screen.  The additional 16 bytes of buffer space required by
  463.          pu_scrnd are not required for this function since it does not
  464.          build the header for the screen region and cursor data.
  465.  
  466.  
  467.          ---------------------------------------------------------------
  468.          rd_scrn -- Read Attrib/Char At Cursor Position
  469.          ---------------------------------------------------------------
  470.             int rd_scrn(void);
  471.  
  472.          Reads the attribute and character at the current cursor pos-
  473.          ition.  The attribute is returned in the upper 8 bits of the
  474.          return value and the character in the lower 8 bits.
  475.  
  476.  
  477.          ---------------------------------------------------------------
  478.          rd_scrnd -- Read Screen String From Specified Location
  479.          ---------------------------------------------------------------
  480.             char *rd_scrnd(int row, int col, int nbytes, char *buf);
  481.  
  482.          Reads a string that is a maximum of 'nbytes' long beginning at
  483.          the specified location.  The string is stored in 'buf' and
  484.          trailing spaces are trimmed.  The 'v_bios' variable does not
  485.          apply to this function.  The return value is a pointer to
  486.          'buf'.
  487.  
  488.          ---------------------------------------------------------------
  489.          cls -- Clear Currently Defined Window
  490.          ---------------------------------------------------------------
  491.             void  cls(void);
  492.  
  493.          Clears the current window using v_color for the attribute.  Re-
  494.          turns nothing.
  495.  
  496.  
  497.          ---------------------------------------------------------------
  498.          scrlup -- Scroll Window Up
  499.          ---------------------------------------------------------------
  500.             void scrlup(int nbrlines);
  501.  
  502.          Scrolls the current window up the specified number of lines.
  503.          The attribute used for blank lines is 'v_color'.
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.          ---------------------------------------------------------------
  511.          scrldn -- Scroll Window Down
  512.          ---------------------------------------------------------------
  513.             void scrldn(int nbrlines);
  514.          Same as previous function except scrolls down.
  515.  
  516.  
  517.          ---------------------------------------------------------------
  518.          scrlupat -- Scroll Specified Area Up
  519.          ---------------------------------------------------------------
  520.             void scrlup(int top, int lft, int btm, int rgt, int nlines);
  521.  
  522.          Same as previous scrlup function except instead of using the
  523.          current window, it scrolls the specified area.
  524.  
  525.  
  526.          ---------------------------------------------------------------
  527.          scrldnat -- Scroll Specified Area Down
  528.          ---------------------------------------------------------------
  529.             void scrldn(int nbrlines);
  530.          Same as previous scrldn function except instead of using the
  531.          current window, it scrolls the specified area.
  532.  
  533.  
  534.          ---------------------------------------------------------------
  535.          setcurloc -- Set Cursor Location
  536.          ---------------------------------------------------------------
  537.             void setcurloc(int location);
  538.  
  539.          Similar to loc(), but this function passes the row and column
  540.          one variable with the upper 8 bits being the row and the lower
  541.          8 bits the column.  This function is used in conjunction with
  542.          getcurloc() to save and restore the cursor position.
  543.  
  544.  
  545.          ---------------------------------------------------------------
  546.          getcurloc -- Get Cursor Location
  547.          ---------------------------------------------------------------
  548.             int getcurloc(void);
  549.  
  550.          Returns the cursor location as an integer.  The upper 8 bits is
  551.          the row, and the lower 8 bits is the column.
  552.  
  553.  
  554.          ---------------------------------------------------------------
  555.          setcursiz -- Set Cursor Size
  556.          ---------------------------------------------------------------
  557.             void setcursiz(int);
  558.  
  559.          Sets the starting and ending scan lines for the cursor. The
  560.          upper 8 bits are the starting scan line and the lower 8 bits
  561.          are the ending scan line.
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.          ---------------------------------------------------------------
  569.          getcursiz -- Get Cursor Size
  570.          ---------------------------------------------------------------
  571.             int getcursiz(void);
  572.  
  573.          Returns the current starting and ending scan lines of the cur-
  574.          sor.  The high bits are the starting scan line and the lower 8
  575.          bits are the ending scan line.
  576.  
  577.  
  578.          ---------------------------------------------------------------
  579.          setvmode -- Set Video Mode
  580.          ---------------------------------------------------------------
  581.             void setvmode(int mode);
  582.  
  583.          Sets the video mode to 'mode'.  The only modes that these func-
  584.          tions will work in, however, are the 80 x 25 text modes.
  585.  
  586.  
  587.          ---------------------------------------------------------------
  588.          getvmode -- Get Video Mode
  589.          ---------------------------------------------------------------
  590.             int getvmode(void);
  591.  
  592.          Returns the current video mode.
  593.  
  594.  
  595.          ---------------------------------------------------------------
  596.          setvpage -- Set Video Page
  597.          ---------------------------------------------------------------
  598.             void setvpage(int page);
  599.  
  600.          Sets the video page to 'page'.  Pages are only supported on
  601.          color systems.  This function also modifies v_seg so that it
  602.          reflects the new page value set.
  603.  
  604.  
  605.          ---------------------------------------------------------------
  606.          getvpage -- Get Video Page
  607.          ---------------------------------------------------------------
  608.             int getvpage(void);
  609.  
  610.          Returns the current video page.
  611.  
  612.  
  613.          ---------------------------------------------------------------
  614.          setvbordr -- Set Video Border
  615.          ---------------------------------------------------------------
  616.             void setvbordr(int attrib);
  617.  
  618.          Sets the border color of the screen.
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.          MISCELLANEOUS FUNCTIONS:
  626.  
  627.          ---------------------------------------------------------------
  628.          str*just -- right, left, or center justify a string.
  629.          ---------------------------------------------------------------
  630.          These functions 1st trim all spaces (ASCII 32's) and then just-
  631.          ify the string in the specified field width using the specified
  632.          pad character.  The memory area where the string is located
  633.          must be at least field size + 1 in size.  If the string is
  634.          longer than the field width, strljust and strcentr truncate the
  635.          right portion of the string; strrjust will cut off the right
  636.          side.  Only ASCII 32's are trimmed.
  637.  
  638.          Returns a pointer to the justified string.
  639.  
  640.          char *strrjust(char *, int, char);
  641.          char *strljust(char *, int, char);
  642.          char *strcentr(char *, int, char);
  643.  
  644.          str_out = strrjust(str_in, fieldsz, padchar);
  645.  
  646.  
  647.          ---------------------------------------------------------------
  648.          str*trim -- trims spaces (ASCII 32's only) from a string.
  649.          ---------------------------------------------------------------
  650.          Trims spaces from left, right, or both ends of a string.
  651.  
  652.          Returns pointer to the passed string.
  653.  
  654.          char *strrtrim(char *);
  655.          char *strltrim(char *);
  656.          char *strtrim(char *);
  657.  
  658.          str_out = strrtrim(str_in);
  659.  
  660.  
  661.          ---------------------------------------------------------------
  662.          strsum -- strcat for multiple strings.
  663.          ---------------------------------------------------------------
  664.          Makes one string from multiple strings.  Unlike strcat, the
  665.          first string in the list is not one of the strings to add but
  666.          instead is a buffer for the result of adding the rest of the
  667.          strings in the list.  The args to the function are:
  668.             the dest, a variable number of char *'s, a NULL ptr
  669.  
  670.          Returns a pointer to the result string.
  671.  
  672.          char *strsum(char *, ...);
  673.  
  674.          str_out = strsum(str_out, str_in1, str_in2, ..., NULL);
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.          ---------------------------------------------------------------
  682.          strpbrkf -- finds 1st char in str1 not in str2.
  683.          ---------------------------------------------------------------
  684.          This function looks for the first character in 'str1' that does
  685.          not belong to the character set contained in 'str2' and returns
  686.          a pointer to that character.  If 'str1' consists entirely of
  687.          characters in 'str2', NULL is returned.  Opposite of strpbrk.
  688.  
  689.          char *strpbrkf(char *, char *);
  690.          rtnstr = strpbrkf(str1, str2);
  691.  
  692.  
  693.          ---------------------------------------------------------------
  694.          strrstr -- find last occurrence of str2 in str1.
  695.          ---------------------------------------------------------------
  696.          This function returns a pointer to the last occurrence of
  697.          'str2' within 'str1'.  If 'str2' is not in 'str1', NULL is
  698.          returned.  This is identical to the standard 'strstr' function
  699.          except it works from the end of 'str1' towards the beginning
  700.          instead of the other way.
  701.  
  702.          char *strrstr(char *, char *);
  703.          rtnstr = strrstr(str1, str2);
  704.  
  705.  
  706.          ---------------------------------------------------------------
  707.          strcntch -- returns number occurrences of char in string.
  708.          ---------------------------------------------------------------
  709.          int strcntchr(char *, char);
  710.          count = strcntchr(string, srchchar);
  711.  
  712.  
  713.          ---------------------------------------------------------------
  714.          calc_crc -- 16 bit CRC routine for block data.
  715.          ---------------------------------------------------------------
  716.          Calculates the CRC for a block of data 'count' bytes long.
  717.          Returns CRC.
  718.  
  719.          int calc_crc(char *, int);
  720.          crc = calc_crc(data, nbr_bytes_of_data);
  721.  
  722.  
  723.          ---------------------------------------------------------------
  724.          update_crc -- 16 bit CRC for character at a time data.
  725.          ---------------------------------------------------------------
  726.          Returns updated CRC.
  727.  
  728.          int update_crc(int, char);
  729.          crc = update_crc(crc, char);
  730.  
  731.  
  732.  
  733.  
  734.  
  735.  
  736.          ---------------------------------------------------------------
  737.          watchdogset -- Enables/Disables watchdog function  (C function)
  738.          watchdoghook -- ASM function used by WATCHDOG.C
  739.          ---------------------------------------------------------------
  740.          int watchdogset(int flag, int combase)
  741.  
  742.          To enable:  call with flag = 1
  743.             combase = base adrs of comm chip (ex: 3F8)
  744.          To disable: call with flag = 0
  745.             combase = don't care
  746.  
  747.          This function monitors Carrier Detect on the selected serial
  748.          port and does a cold reboot if the carrier is lost.  If you use
  749.          both this function and the TIMEOUT functions make sure you
  750.          uninstall the hooks in the reverse order that you installed
  751.          them and make sure that you uninstall them before you exit your
  752.          program.  Failing to do this will cause your system to crash
  753.          (the redirected interrupt vectors are now pointing to freed
  754.          memory instead of a program).
  755.  
  756.  
  757.          ---------------------------------------------------------------
  758.          ctshookset -- Patch to BIOS INT14 to prevent timeouts when
  759.             using CTS handshaking  (C function)
  760.          int14ctshook -- ASM function used with CTSHOOKSET
  761.          ---------------------------------------------------------------
  762.          int ctshookset(int flag, int portval, int combase)
  763.          void interrupt far int14ctshook(void);
  764.  
  765.          To enable:  call with flag = 1
  766.             portval = COM1 (0) or COM2 (1)
  767.             combase = base adrs of comm chip (ex: 3F8)
  768.          To disable: call with flag = 0
  769.             portval = don't care
  770.             combase = don't care
  771.  
  772.          This function sets a hook into the BIOS serial interrupt vector
  773.          that waits indefinitely for CTS to go high on the specified
  774.          port when sending data.  All INT14 calls that are not for the
  775.          specified port and all service requests except for 'send byte'
  776.          are passed on to the old INT14 vector unaltered.  In other
  777.          words for the hook to have any effect when INT14 is called:
  778.             1)  DX has to equal the 'portval' you set here
  779.             2)  AH has to equal '1' -- the send char service ID
  780.          The effect it has then is to wait for CTS to be true then exe-
  781.          cute the old INT14 interrupt.  The purpose of the function is
  782.          keep high speed modems that CTS handshake from creating timeout
  783.          errors when redirecting stdout and stderr to the comm port.  Be
  784.          SURE to uninstall the hook before exiting your program or the
  785.          redirected interrupt vector will be pointing to free memory
  786.          instead of an interrupt handler.
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.          ---------------------------------------------------------------
  794.          tickhookset -- Enables/Disables 'ticker' for timer functions
  795.          ---------------------------------------------------------------
  796.          int tickhookset(int flag)
  797.  
  798.          To enable:  call with flag = 1
  799.          To disable: call with flag = 0
  800.  
  801.          This function enables the 'tick counter' used by the timeout
  802.          and tdelay functions by pointing the TIMER interrupt vector,
  803.          1Ch, to a new interrupt handler that increments the counter
  804.          approximately 18.2 times per second.  The advantage of using
  805.          this method over the BIOS function is no coding is needed to
  806.          account for the possibility of calling your timer functions
  807.          near midnight.  The 'tick counter' is a long and may be read by
  808.          calling 'get_ticker'.
  809.  
  810.          YOU MUST DISABLE 'TICKER' BEFORE EXITING YOUR PROGRAM.
  811.  
  812.  
  813.          ---------------------------------------------------------------
  814.          set_timeout     -- initializes a timer
  815.          set_longtimeout -- initialize a long timer
  816.          timed_out       -- checks if a timeout has occurred
  817.          ---------------------------------------------------------------
  818.          void set_timeout(long *t_out, unsigned ticks);
  819.  
  820.          int timed_out(long *t_out);
  821.  
  822.          These functions work in conjunction with each other and require
  823.          the 'tick counter' to be activated by TICKHOOKSET.  The fol-
  824.          lowing macros are defined in EXTRA.H:
  825.             SET_TO_TENTHS(to, tenths)  set_timeout((&to), (tenths)*9/5)
  826.             SET_TO_SECS(to, secs)      set_timeout((&to), (secs)*18)
  827.             SET_TO_MINS(to, mins)      set_timeout((&to), (mins)*1080)
  828.          After setting the timeout value with one of the above macros
  829.          you then call timed_out() see if a timeout has occurred.  Here
  830.          is an example:
  831.  
  832.             long to;
  833.             int toolong = 0;
  834.  
  835.             tickhookset(1);                      /* enable hook */
  836.             SET_TO_SECS(to, 2);       /* set timeout for 2 secs */
  837.             while (!(toolong = timed_out(&to)))
  838.             {
  839.                if (condition_met()) /* wait for cond 2 secs max */
  840.                   break;
  841.             }
  842.             if (toolong)             /* timed out if toolong NZ */
  843.                return TIMEOUT_ERR;
  844.  
  845.          Notice that the macro does not require the '&' operator but the
  846.          call to timed_out() does.  Using these functions, you may have
  847.          as many timeouts going as you have timeout variables.
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.          ---------------------------------------------------------------
  855.          get_ticker -- get the current value of internal tick counter
  856.          ---------------------------------------------------------------
  857.          long get_ticker(void);
  858.  
  859.          Returns the value of the internal tick counter.  This counter
  860.          is incremented 18.2 times a second from the time tickhookset(1)
  861.          is called until tickhookset(0) is called.
  862.  
  863.  
  864.          ---------------------------------------------------------------
  865.          tdelay -- kill time function
  866.          ---------------------------------------------------------------
  867.          int tdelay(unsigned ticks);
  868.  
  869.          This functions delays the specified number of ticks and then
  870.          returns.  Before using this function you must enable the
  871.          internal tick counter by calling 'tickhookset'.
  872.  
  873.          The following macros are defined in EXTRA.H:
  874.             DELAY_TENTHS(tenths)     tdelay(((tenths)*9/5)+1)
  875.             DELAY_SECS(secs)         tdelay((secs)*18)
  876.             DELAY_MINS(mins)         tdelay((mins)*1080)
  877.  
  878.